import i18n, { i18n as I18nInstance, TFunction } from 'i18next';
import { initReactI18next } from 'react-i18next';

import { localStg } from '@/utils/storage';

import locales from './locale';

/**
 * i18n 实例，负责多语言环境的初始化与切换
 * 类型：I18nInstance
 */
export const reactI18nextInstance: I18nInstance = i18n.use(initReactI18next);

/**
 * 初始化 i18n 插件，设置默认语言和资源
 * @async
 * @returns {Promise<void>} 无返回值
 */
export async function setupI18n(): Promise<void> {
	await reactI18nextInstance.init({
		interpolation: {
			escapeValue: false // 不对输出内容进行转义，防止 XSS
		},
		lng: localStg.get('lang', 'zh-CN'), // 默认语言优先取本地存储
		resources: locales // 多语言资源对象
	});
}

/**
 * 全局多语言翻译函数，类型为 TFunction
 * 用法：$t('key')
 */
export const $t: TFunction = reactI18nextInstance.t.bind(reactI18nextInstance);

/**
 * 切换当前语言
 * @param {App.I18n.LangType} locale - 目标语言类型（如 'zh-CN' | 'en-US'）
 * @returns {Promise<void>} 无返回值
 */
export function setLng(locale: App.I18n.LangType): void {
	reactI18nextInstance.changeLanguage(locale);
}

/**
 * ========================= 典型用法示例 =========================
 *
 * // 1. 初始化多语言环境（通常在应用入口调用）
 * import { setupI18n } from '@/locales';
 * await setupI18n();
 *
 * // 2. 获取翻译文本
 * import { $t } from '@/locales';
 * const hello = $t('common.hello');
 *
 * // 3. 切换语言
 * import { setLng } from '@/locales';
 * setLng('en-US');
 *
 * // 4. 推荐在 React 组件中使用 useTranslation 钩子
 * import { useTranslation } from 'react-i18next';
 * const { t } = useTranslation();
 * <span>{t('common.hello')}</span>
 *
 * =============================================================
 *
 * 说明：
 * - 本文件封装了 i18n 的初始化、翻译和切换语言能力，建议全局唯一引用。
 * - $t 适合在非 React 组件环境下直接调用，组件内建议用 useTranslation。
 * - 语言类型 App.I18n.LangType 需在全局类型定义中声明。
 */
// ========================= 文件结束 =========================
